2022 iThome 鐵人賽

DAY 26

Software Development

ClickHouse:時序資料庫建置與運行系列第 26 篇

day26-ClickHouse 客戶端連線介面方式(五)

14th鐵人賽

peter279k

2022-10-10 01:58:04

1247 瀏覽

分享至

前言

在本章節中，將繼續介紹其他的客戶端連線函式庫。

官方的客戶端連線函式庫

ClickHouse官方除了提供ODBC、JDBC與C++函式庫的連線之外，另外還提供了其他程式語言的函式庫連線，相關的程式語言函式庫如下列表：

clickhouse-http-client, 官方提供的Java之HTTP協定為基礎的資料庫客戶端連線函式庫。
clickhouse-js, 官方提供的JavaScript之資料庫客戶端連線函式庫。
clickhouse-go, 官方提供Golang Driver（屬於高階high-level方式）之資料庫客戶端連線函式庫。
ch-go, 官方提供低階（low-level）Go之資料庫客戶端連線函式庫。
clickhouse-connect, 官方提供的Python資料庫客戶端連線函式庫。

上述的函式庫列表的專案連結會列在參考資料中。

官方的Java客戶端之HTTP為基礎的函式庫建置與應用

在這邊先假設已經安裝與建置好Java的環境，這邊以Ubuntu 18.04的Linux版本發行的作業系統為例，已經在目標的作業系統上安裝好Java之JDK版本11與Maven版本為3.6.0。

若沒有建置好的話，可以先參考之前有關於JDBC應用範例的章節將所需要的Java環境安裝起來，接著執行下列的指令將範例專案透過git clone指令從GitHub上的儲存庫複製回來：

同時確定ClickHouse資料庫有安裝在本地的機器，若沒有的話，則可以參考前面的章節進行ClickHouse資料庫的安裝。

peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~$ git clone https://github.com/peter279k/hello-clickhouse-client
Cloning into 'hello-clickhouse-client'...
remote: Enumerating objects: 15, done.
remote: Counting objects: 100% (15/15), done.
remote: Compressing objects: 100% (8/8), done.
remote: Total 15 (delta 2), reused 15 (delta 2), pack-reused 0
Unpacking objects: 100% (15/15), done.

切換到該專案目錄底下之後，接著可以執行下列的vim指令當作範例，將HelloDB.java檔案進行編輯，修改程式碼中第13行的password值變成我們自己的密碼。

接著執行所需要的相依函式庫安裝與編譯指令，相關的執行指令與輸出的訊息如下：

peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~$ cd hello-clickhouse-client/
peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~/hello-clickhouse-client$ vim src/main/java/hello/HelloDB.java
peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~/hello-clickhouse-client$ mvn compile
......
[INFO] Compiling 1 source file to /home/peter/hello-clickhouse-client/target/classes
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  1.483 s
[INFO] Finished at: 2022-10-06T03:15:00Z
[INFO] ------------------------------------------------------------------------
peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~/hello-clickhouse-client$

在這個範例中，使用到的是clickhouse-http-client這個函式庫，若要修改相依版本的話，則可以編輯pom.xml之第21行內容進行版本的修改，修改完後需要再次執行mvn compile指令。

完成上述安裝相依函式庫與編譯Java程式碼之後，接著可以執行mvn package指令將編譯成byte-code的程式封裝成JAR檔，相關的執行指令與輸出的訊息如下：

peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~/hello-clickhouse-client$ mvn package
......
[INFO] Dependency-reduced POM written at: /home/peter/hello-clickhouse-client/dependency-reduced-pom.xml
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  1.624 s
[INFO] Finished at: 2022-10-06T03:26:28Z
[INFO] ------------------------------------------------------------------------
peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~/hello-clickhouse-client$

完成上述的JAR封裝的動作之後，接著可以使用下列指令執行封裝好的JAR檔，相關的執行指令與輸出的訊息如下：

peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~/hello-clickhouse-client$ java -jar target/hello-clickhouse-client-0.1.0.jar
0
1
2
3
4
5
6
7
8
9

這樣就代表成功的執行範例程式碼了，範例程式碼執行的是select * from numbers(10)之SQL語句並把結果的值依序的輸出，就會得到與上述一樣的輸出訊息了。

官方的JS客戶端之HTTP為基礎的函式庫建置與應用

在使用JS客戶端範例之前，需要安裝Node.js的環境，我們可以使用nvm來安裝與管理主機上我們要的Node.js版本，相關的執行指令與輸出的訊息如下：

peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100 15037  100 15037    0     0   772k      0 --:--:-- --:--:-- --:--:--  772k
=> Downloading nvm from git to '/home/peter/.nvm'
=> Cloning into '/home/peter/.nvm'...
remote: Enumerating objects: 355, done.
remote: Counting objects: 100% (355/355), done.
remote: Compressing objects: 100% (302/302), done.
remote: Total 355 (delta 39), reused 169 (delta 28), pack-reused 0
Receiving objects: 100% (355/355), 221.39 KiB | 10.54 MiB/s, done.
Resolving deltas: 100% (39/39), done.
* (HEAD detached at FETCH_HEAD)
  master
=> Compressing and cleaning up git repository

=> Appending nvm source string to /home/peter/.bashrc
=> Appending bash_completion source string to /home/peter/.bashrc
=> Close and reopen your terminal to start using nvm or run the following to use it now:

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"  # This loads nvm
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"  # This loads nvm bash_completion
peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~$ source ~/.bashrc
peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~$ nvm list
            N/A
iojs -> N/A (default)
node -> stable (-> N/A) (default)
unstable -> N/A (default)
peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~$

安裝好nvm後，接著可以執行下列的指令安裝目前Node.js的LTS版本，即長期支援的意思，執行指令與輸出的訊息如下：

peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~$ nvm install --lts
Installing latest LTS version.
Downloading and installing node v16.17.1...
Downloading https://nodejs.org/dist/v16.17.1/node-v16.17.1-linux-x64.tar.xz...
##################################################################################################### 100.0%
Computing checksum with sha256sum
Checksums matched!
Now using node v16.17.1 (npm v8.15.0)
Creating default alias: default -> lts/* (-> v16.17.1)
peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~$ node --version
v16.17.1
peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~$ npm --version
8.15.0
peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~$

安裝好Node.js版本之後，執行下列指令進行該JS客戶端套件安裝以及安裝ts-node套件，可以將TypeScript轉成Node.js程式碼進行執行，執行指令所輸出的訊息如下：

peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~$ npm i @clickhouse/client

added 2 packages, and audited 3 packages in 3s

found 0 vulnerabilities
npm notice
npm notice New minor version of npm available! 8.15.0 -> 8.19.2
npm notice Changelog: https://github.com/npm/cli/releases/tag/v8.19.2
npm notice Run npm install -g npm@8.19.2 to update!
npm notice
peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~$ npm -g i ts-node

added 19 packages, and audited 22 packages in 4s

found 0 vulnerabilities
peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~$ ts-node --version
v10.9.1

執行完成安裝JS之套件之後，使用編輯器並編輯一個檔案叫做client.ts，下列以vim編輯器為示範，相關執行指令與輸出的訊息如下：

peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~$ vim client.ts
peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~$ cat client.ts
import { createClient } from '@clickhouse/client'
void (async () => {
  const client = createClient({
    host: 'http://127.0.0.1:8123?user=peter',
    username: 'default',
    password: 'password',
    database: 'default',
  })
  const rows = await client.query({
    query: 'SELECT number FROM numbers(10)',
    format: 'JSONEachRow',
    clickhouse_settings: {
      // See ClickHouseSettings typings
      connect_timeout: 30,
    },
  })
  console.info(await rows.json())
  await client.close()
})()
peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~$

從上面輸出的訊息可以知道，首先先用vim文字編輯器進行client.ts檔案的編輯，接著使用cat指令將編輯的檔案進行輸出，其中，記得password需要修改成使用者的密碼。

完成之後，使用下列指令可以執行上述的程式碼，相關執行指令與輸出的訊息如下：

peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~$ ts-node client.ts
[
  { number: '0' },
  { number: '1' },
  { number: '2' },
  { number: '3' },
  { number: '4' },
  { number: '5' },
  { number: '6' },
  { number: '7' },
  { number: '8' },
  { number: '9' }
]

更多的範例與設定可以在下列的連結中找到：

官方的Go客戶端之低階函式庫建置與應用

在執行Go相關的程式範例之前，需要先建置好可以執行Go程式語言的環境，這邊以Ubuntu 18.04之Linux發行版本的作業系統為例，相關執行Go程式語言建置指令如下：

peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~$ sudo add-apt-repository ppa:longsleep/golang-backports
peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~$ sudo apt-get install golang-1.18-go

從上述的指令可以知道，我們引用了外部的儲存庫longsleep/golang-backports並安裝Go之1.18的版本，安裝好之後，執行go的指令會放在如下的路徑，相關執行指令與輸出的訊息如下：

peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~$ /usr/lib/go-1.18/bin/go version
go version go1.18.5 linux/amd64

安裝好Go程式語言之後，接下來要設定給Go程式語言需要設定環境變數來指定需要使用的路徑：

peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~$ mkdir go-ch-client
peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~$ export GOPATH=$HOME/go-ch-client
peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~$ export GOBIN=$GOPATH/bin
peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~$ export PATH=$PATH:$GOPATH/bin
peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~$ export GOROOT=/usr/lib/go-1.18
peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~$ export PATH=$PATH:$GOROOT/bin
peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~$ go version
go version go1.18.5 linux/amd64
peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~$ go env | grep -E "GOPATH|GOBIN|GOROOT"
GOBIN="/home/peter/go-ch-client/bin"
GOPATH="/home/peter/go-ch-client"
GOROOT="/usr/lib/go-1.18"
peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~$

從上面的輸出訊息可以知道，先建立go-ch-client目錄當作我們的Go程式語言工作路徑，有關於設定環境變數的指令（即export）也可以都加入到家目錄底下的.bashrc檔案中，這樣在啟動終端機的時候，這些環境變數就會自動的增加或是覆寫既有的環境變數設定了，同時我們也不需要在每次開啟終端機的時候去重複的執行這些環境變數設定的指令。

再使用export指令分別設定GOPATH、GOBIN與GOROOT環境變數，並覆寫既有的PATH環境變數，完成好設定之後，可以使用go version指令檢查變數是否有設定成功。

以及使用go env指令檢查幾個設定的環境變數是否有順利的設定完成，接著執行下列指令建立範例專案目錄、設定檔以及將我們需要的Go套件進行下載，相關執行的指令與輸出的訊息如下：

peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~$ mkdir go-client/
peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~$ cd go-client
peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~/go-client$ echo "module github.com/peter279k/go-client" > go.mod
peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~/go-client$ echo "" >> go.mod
peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~/go-client$ echo "go 1.18" >> go.mod
peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~/go-client$ cat go.mod
module github.com/peter279k/go-client

go 1.18
peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~/go-client$ go get github.com/ClickHouse/ch-go@latest
go: downloading github.com/ClickHouse/ch-go v0.48.0
go: downloading github.com/dmarkham/enumer v1.5.6
......
go: added golang.org/x/sync v0.0.0-20220722155255-886fb9371eb4
go: added golang.org/x/sys v0.0.0-20220811171246-fbc7d0a398ab
go: added golang.org/x/tools v0.1.12
peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~/go-client$

在設定go.mod檔案時候，第一行的github.com/peter279k/go-client指的是名稱，可以替換成自己要取的名稱，例如：example.com/module_name。

上述這個Go套件是利用TCP協定連線與ClickHouse資料庫進行溝通與存取的因此屬於低層級（low-level）的連線方式，安裝好套件之後使用文字編輯器編輯client.go檔案，下列以vim編輯為例進行編輯，執行指令與輸出訊息如下：

peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~/go-client$ vim client.go

使用上述的文字編輯器完成程式碼編輯之後，可以看一下我們編輯的Go程式碼：

package main

import (
  "context"
  "fmt"

  "github.com/ClickHouse/ch-go"
  "github.com/ClickHouse/ch-go/proto"
)

func main() {
  ctx := context.Background()
  c, err := ch.Dial(ctx, ch.Options{
    Address: "localhost:9000",
    User: "default",
    Password: "password",
    Database: "default",
  })
  if err != nil {
    panic(err)
  }
  var (
    numbers int
    data    proto.ColUInt64
  )
  if err := c.Do(ctx, ch.Query{
    Body: "SELECT number FROM numbers(10)",
    Result: proto.Results{
      {Name: "number", Data: &data},
    },
    // OnResult will be called on next received data block.
    OnResult: func(ctx context.Context, b proto.Block) error {
      numbers += len(data)
      return nil
    },
  }); err != nil {
    panic(err)
  }
  fmt.Println("numbers:", numbers)
}

從上述的程式碼可以得知，使用9000的埠號連上的就是ClickHouse資料庫客戶端使用的TCP協定進行連線，連線成功之後執行SELECT number FROM numbers(10)之SQL語句，最後輸出印出的筆數。要注意的是，Password所對應的password記得修改成自己的資料庫密碼。

編寫完成上述的程式碼之後，接著執行下列的指令以執行該Go程式，相關執行指令所輸出的訊息如下：

peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~/go-client$ go run client.go
numbers: 10
peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~/go-client$

更多的範例與用法可以參考此連結：https://github.com/ClickHouse/ch-go

官方的Go客戶端之高階函式庫建置與應用

另外一個是有關於高階的方式存取ClickHouse資料庫的Go套件，假設已經安裝與設定好Go語言環境，若沒有的話，可以先參考上一個低階的Go套件建置與運行的範例。

我們沿用上一個專案目錄，即go-client，接著執行下列指令將該套件安裝起來，相關的執行指令與輸出的訊息如下：

peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~/go-client$ go get github.com/ClickHouse/clickhouse-go/v2
go: downloading github.com/ClickHouse/clickhouse-go/v2 v2.3.0
go: downloading github.com/andybalholm/brotli v1.0.4
go: downloading github.com/pkg/errors v0.9.1
go: downloading github.com/paulmach/orb v0.7.1
go: downloading github.com/shopspring/decimal v1.3.1
go: added github.com/ClickHouse/clickhouse-go/v2 v2.3.0
go: added github.com/andybalholm/brotli v1.0.4
go: added github.com/paulmach/orb v0.7.1
go: upgraded github.com/pkg/errors v0.8.1 => v0.9.1
go: added github.com/shopspring/decimal v1.3.1

安裝好套件之後，使用vim編輯器編輯client2.go之檔案，相關的執行指令與輸出的訊息如下：

peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~/go-client$ vim client2.go

編輯上述檔案中的Go程式碼如下：

package main

import (
  "fmt"
  "context"
  "github.com/ClickHouse/clickhouse-go/v2"
)

func main() {
  conn, err := clickhouse.Open(&clickhouse.Options{
    Addr: []string{fmt.Sprintf("%s:%d", "127.0.0.1", 9000)},
    Auth: clickhouse.Auth{
      Database: "default",
      Username: "default",
      Password: "password",
    },
  })

  if err != nil {
    panic(err)
  }

  row := conn.QueryRow(context.Background(), "SELECT version() as version")
  var (
    version string
  )
  if err := row.Scan(&version); err != nil {
    panic(err)
  }
  fmt.Printf("row: DB version is %s\n", version)
}

其中上述的程式碼的Password所對應的password需要改成確切的使用者資料庫密碼，編輯好上述的程式碼之後，執行該程式，執行指令與輸出的訊息如下：

peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~/go-client$ go run client2.go
row: DB version is 22.8.4.7
peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~/go-client$

上面的程式是取得查詢完之後的第一筆資料，若要查詢多筆資料的話，則需要將client2.go之程式碼改成如下：

package main

import (
  "fmt"
  "context"
  "github.com/ClickHouse/clickhouse-go/v2"
)

func main() {
  conn, err := clickhouse.Open(&clickhouse.Options{
    Addr: []string{fmt.Sprintf("%s:%d", "127.0.0.1", 9000)},
    Auth: clickhouse.Auth{
      Database: "default",
      Username: "default",
      Password: "password",
    },
  })

  if err != nil {
    panic(err)
  }

  rows, err := conn.Query(context.Background(), "SELECT number FROM numbers(10)")
  if err != nil {
    panic(err)
  }

  for rows.Next() {
    var (
      number uint64
    )
    if err := rows.Scan(&number); err != nil {
      panic(err)
    }
    fmt.Printf("row: number=%d\n", number)
  }
  rows.Close()

  if rows.Err() != nil {
    panic(rows.Err())
  }
}

上述程式碼就是改成查詢語句的結果有多行的時候，進行取值與輸出值的方式，編輯好新的程式碼後，執行下列的指令就會看到如下的結果了：

peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~/go-client$ go run client2.go
row: number=0
row: number=1
row: number=2
row: number=3
row: number=4
row: number=5
row: number=6
row: number=7
row: number=8
row: number=9
peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~/go-client$

更多有關於此Go套件的用法範例可以參考下列幾個連結：

官方的Python客戶端函式庫建置與應用

此Python套件需要Python版本3.7以上並安裝有Cython，若以Ubuntu 18.04為例的話，內建Python版本為3.6.9，因此需要引入外部的儲存庫安裝新的Python套件，以及設定連結的python3與pip3的指令，相關執行上述的指令與輸出的訊息如下：

peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~$ sudo add-apt-repository -y ppa:deadsnakes/ppa
......
Get:1 http://mirrors.digitalocean.com/ubuntu bionic InRelease [242 kB]
Hit:2 http://mirrors.digitalocean.com/ubuntu bionic-updates InRelease
Hit:3 http://mirrors.digitalocean.com/ubuntu bionic-backports InRelease
Hit:4 https://packages.clickhouse.com/deb stable InRelease
......
Fetched 242 kB in 2s (155 kB/s)
Reading package lists... Done
peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~$ sudo apt-get install python3.7 python3.7-dev -y
......
Processing triggers for desktop-file-utils (0.23-1ubuntu3.18.04.2) ...
Processing triggers for man-db (2.8.3-2ubuntu0.1) ...
peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~$ python3.7
Python 3.7.14 (default, Sep  8 2022, 00:06:44)
[GCC 7.5.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> quit()
peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~$ python3.7 -m pip install pip --user
Collecting pip
  Downloading https://files.pythonhosted.org/packages/1f/2c/d9626f045e7b49a6225c6b09257861f24da78f4e5f23af2ddbdf852c99b8/pip-22.2.2-py3-none-any.whl (2.0MB)
    100% |████████████████████████████████| 2.0MB 539kB/s
Installing collected packages: pip
Successfully installed pip-22.2.2
peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~$ python3.7 -m pip --version
pip 22.2.2 from /home/peter/.local/lib/python3.7/site-packages/pip (python 3.7)
peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~$ alias pip3.7="python3.7 -m pip"
peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~$ pip3.7 --version
pip 22.2.2 from /home/peter/.local/lib/python3.7/site-packages/pip (python 3.7)

從上述的執行指令與輸出的訊息可以知道，我們依序做了下列的事情：

引入ppa:deadsnakes/ppa之專案庫，並安裝Python 3.7的版本，安裝python-3.7-dev是因為後續的安裝Cython需要使用到。
執行python3.7確認Python 3.7版本已經有使用了，確認完之後使用quit()離開此互動式的shell。
接著執行python3.7 -m pip install pip -U以安裝pip來管理Python套件的指令，並安裝到當前使用者的目錄。
當安裝完成後，執行python3.7 -m pip --version確認pip有安裝完成。
使用alias設定將python3.7 -m pip指令別名為pip3.7，這樣可以減少輸入指令的不便。
- 同時這行也可以設定到使用者家目錄的.bashrc檔案裡面，這樣就可以在開啟新的終端機之後，該別名的設定就會自動執行，我們就不用每次在開啟新的終端機都要重新執行別名設定指令了。

設定完成之後，接著要安裝Cython，這是一個用來加速Python程式碼的套件，在使用pip安裝之前需要確認gcc指令可以使用，即C的編譯器，若沒有的話，則需要先執行下列的指令：

sudo apt-get install -y build-essential

接著才可以執行下列的指令，因為先前已經用別名設定過了，所以直接使用pip3.7來安裝cython，相關的執行指令與輸出的訊息如下：

peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~$ pip3.7 install cython --user
Collecting cython
  Downloading Cython-0.29.32-cp37-cp37m-manylinux_2_17_x86_64.manylinux2014_x86_64.manylinux_2_24_x86_64.whl (1.9 MB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1.9/1.9 MB 37.0 MB/s eta 0:00:00
Installing collected packages: cython
  WARNING: The scripts cygdb, cython and cythonize are installed in '/home/peter/.local/bin' which is not on PATH.
  Consider adding this directory to PATH or, if you prefer to suppress this warning, use --no-warn-script-location.
Successfully installed cython-0.29.32

安裝好cython之後，執行pip3.7 install clickhouse-connect --user指令進行此Python套件的安裝，相關執行指令與輸出的訊息如下：

peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~$ pip3.7 install clickhouse-connect --user
Collecting clickhouse-connect
  Downloading clickhouse_connect-0.2.10-cp37-cp37m-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl (183 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 183.4/183.4 kB 14.3 MB/s eta 0:00:00
Requirement already satisfied: requests in /usr/lib/python3/dist-packages (from clickhouse-connect) (2.18.4)
Requirement already satisfied: pytz in /usr/lib/python3/dist-packages (from clickhouse-connect) (2018.3)
Installing collected packages: clickhouse-connect
Successfully installed clickhouse-connect-0.2.10
peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~$

接著編輯一個Python程式碼檔案叫做client_py.py，以下用vim文字編輯器進行編輯，相關執行指令與輸出的訊息如下：

vim client_py.py

所編輯的Python程式碼如下：

import clickhouse_connect


client = clickhouse_connect.get_client(host='play.clickhouse.com', port=443, username='play')
query_result = client.query('SHOW TABLES')
print (query_result.result_set)

執行上述編輯好的程式碼，相關執行程式碼與輸出的訊息如下：

peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~$ python3.7 client_py.py
[('benchmark_results',), ('benchmark_runs',), ('cell_towers',), ('checks',), ('covid',), ('dish',), ('dns',), ('dns2',), ('food_facts',), ('github_events',), ('hackernews',), ('hits',), ('hits_100m_compatible',), ('hits_100m_obfuscated',), ('lineorder',), ('loc_stats',), ('menu',), ('menu_item',), ('menu_item_denorm',), ('menu_page',), ('minicrawl',), ('ontime',), ('opensky',), ('primes',), ('query_metrics_v2',), ('rdns',), ('recipes',), ('reddit',), ('repos',), ('repos_raw',), ('run_attributes_v1',), ('stock',), ('tokens',), ('trips',), ('uk_price_paid',), ('wikistat',)]

從上述的程式碼可以得知，我們先透過HTTP協定連到遠端的play.clickhouse.com主機資料庫，並使用play使用者進行登入資料庫，接著執行SHOW TABLES將遠端該當前資料庫中的資料表清單輸出。

在本地端已經有安裝了ClickHouse資料庫伺服器，若要改成連到本地端的ClickHouse資料庫，則可以改成下列的程式碼：

import clickhouse_connect


client = clickhouse_connect.get_client(
    host='127.0.0.1',
    port=8123,
    username='default',
    password='password',
    database='default',
)
query_result = client.query('SHOW TABLES')
print (query_result.result_set)

從上述的程式碼可以得知，password需要改成當前資料庫的使用者密碼，接著執行該Python程式碼，相關執行程式所輸出的訊息如下：

peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~$ python3.7 client_py.py
[('describe_example',), ('example_back',), ('grpc_example_table',), ('insert_select_testtable',), ('limit_by',), ('simple_table',), ('t1',), ('t2',), ('table_from_file',), ('table_with_comment',), ('table_with_ttl',), ('temp',), ('ttt',)]

更多的範例用法可以參考該專案中的README.md檔案，連結：https://github.com/ClickHouse/clickhouse-connect。